---
type: integration
title: '@astrojs/node'
description: '@astrojs/node 어댑터를 사용하여 Astro 프로젝트를 배포하는 방법을 알아보세요.'
sidebar:
  label: Node
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/node/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import Since from '~/components/Since.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';

이 어댑터를 사용하면 Astro가 [서버 아일랜드](/ko/guides/server-islands/), [액션](/ko/guides/actions/), [세션](/ko/guides/sessions/)을 포함하여 [요청 시 렌더링되는 라우트 및 기능](/ko/guides/on-demand-rendering/)을 Node 대상에 배포할 수 있습니다.

Astro를 정적 사이트 빌더로 사용하는 경우에는 어댑터가 필요하지 않습니다.

## 왜 Astro Node.js인가?

[Node.js](https://nodejs.org/ko/)는 서버 측 코드를 위한 JavaScript 런타임입니다. @astrojs/node는 standalone 모드에서 사용하거나 [Express](https://expressjs.com/)와 같은 다른 http 서버의 미들웨어로 사용할 수 있습니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

`astro add` 명령을 사용하여 Astro 프로젝트에서 요청 시 렌더링을 활성화하려면 Node 어댑터를 추가하세요.
그러면 `@astrojs/node`가 설치되고 `astro.config.*` 파일이 한 번에 적절하게 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add node
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add node
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add node
  ```
  </Fragment>
</PackageManagerTabs>

이제 [페이지별로 요청 시 렌더링](/ko/guides/on-demand-rendering/#요청-시-렌더링-활성화)을 활성화하거나, [기본적으로 모든 페이지를 서버 렌더링](/ko/guides/on-demand-rendering/#server-모드)하도록 빌드 출력 구성을 `output: 'server'`로 설정할 수 있습니다.

### 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트의 종속성에 Node 어댑터를 추가하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/node
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/node
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/node
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `astro.config.*` 파일에 어댑터를 추가합니다.

```js title="astro.config.mjs" ins={2,5-7}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
});
```

## 구성

@astrojs/node는 옵션을 어댑터 함수에 전달하여 구성할 수 있습니다. 다음 옵션을 사용할 수 있습니다.

### `mode`
<p>
**타입:** `'middleware' | 'standalone'` <br />
</p>

어댑터가 `middleware` 또는 `standalone` 모드로 빌드되는지 여부를 제어합니다.

* `middleware` 모드를 사용하면 빌드된 출력을 Express.js 또는 Fastify와 같은 다른 Node.js 서버의 미들웨어로 사용할 수 있습니다.
* `standalone` 모드는 진입점 모듈이 실행될 때 자동으로 시작되는 서버를 빌드합니다. 이를 통해 추가 코드 없이 빌드 결과를 호스트에 더 쉽게 배포할 수 있습니다.

```js title="astro.config.mjs" {6}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'middleware',
  }),
});
```

### `experimentalDisableStreaming`

<p>
**타입:** `boolean` <br />
**기본값:** `false`<br />
<Since v="9.3.0" pkg="@astrojs/node" />
</p>

요청 시 렌더링되는 페이지에 대해 Astro의 기본 [HTML 스트리밍](/ko/guides/on-demand-rendering/#html-스트리밍)을 비활성화합니다.

HTML 스트리밍은 성능에 도움이 되며 일반적으로 방문자에게 더 나은 경험을 제공합니다. 대부분의 경우 스트리밍을 비활성화하는 것은 권장되지 않습니다.

하지만 HTML 스트리밍을 비활성화해야 하는 경우 (예: 호스트가 CDN 수준에서 스트리밍되지 않는 HTML 캐싱만 지원하는 경우) 기본 동작을 비활성화할 수 있습니다.

```js title="astro.config.mjs" {7}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
    experimentalDisableStreaming: true,
  }),
});
```

### `experimentalStaticHeaders`

<p>
  **타입:** `boolean` <br />
  **기본값:** `false`<br />
  <Since v="9.3.0"  pkg="@astrojs/node"/>
</p>

이 기능이 활성화되면, Astro 기능 (예: 콘텐츠 보안 정책)에서 제공하는 경우 어댑터는 `Response` 객체를 사용하여 사전 렌더링된 페이지의 헤더를 제공합니다.

예를 들어, [실험적인 콘텐츠 보안 정책](/ko/reference/experimental-flags/csp/)이 활성화된 경우, `<meta>` 요소를 생성하는 대신 `experimentalStaticHeaders`를 사용하여 CSP 헤더를 `Response` 객체에 추가할 수 있습니다.

```js title="astro.config.mjs" {10}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: node({
    mode: 'standalone',
    experimentalStaticHeaders: true,
  })
});
```

### `experimentalErrorPageHost`

<p>
  **타입:** `string | URL` <br />
  **기본값:** `undefined`<br />
  <Since v="9.4.0" pkg="@astrojs/node"/>
</p>

미리 렌더링된 [사용자 정의 오류 페이지](/ko/basics/astro-pages/#사용자-정의-404-오류-페이지)를 로드하기 위한 대체 호스트를 지정합니다.

응답으로 404 페이지를 반환하려면 Astro가 404 페이지를 로드할 수 있어야 합니다. 기본적으로 Astro는 요청이 이루어진 호스트와 동일한 호스트에서 미리 렌더링된 사용자 정의 오류 페이지를 로드합니다. 예를 들어 `https://example.com/nonexistent-page`에서 요청이 생성된 경우 Astro는 `https://example.com/404.html`에서 미리 렌더링된 오류 페이지를 로드하려고 시도합니다.

서버가 역방향 프록시 뒤에서 실행 중이거나 외부 호스트 URL에 액세스할 수 없는 컨테이너에서 실행되는 경우와 같이 사용자 정의 오류 페이지를 다른 호스트에서 로드해야 하는 경우 `experimentalErrorPageHost`를 사용하세요. 또한 공용 인터넷이 아닌 로컬 호스트에서 미리 렌더링된 오류 페이지를 로드하는 것이 더 효율적인 경우에도 이 옵션을 사용할 수 있습니다.

값은 문자열 또는 URL 객체일 수 있습니다. 프로토콜을 포함하여 정규화된 URL (예: `http://localhost:4321`)이어야 합니다. Astro는 항상 루트 경로에서 미리 렌더링된 오류 페이지를 로드하며 경로 또는 쿼리 매개 변수는 무시됩니다.

```js
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    // 공개 URL이 아닌 로컬 호스트에서 페이지를 로드합니다.
    experimentalErrorPageHost: 'http://localhost:4321',
  })
});
```

## 사용하기

먼저 [빌드를 수행](/ko/guides/deploy/#사이트를-로컬로-빌드)합니다. 선택한 모드 (위 참조)에 따라 아래의 적절한 단계를 따르세요.

### 미들웨어

서버 엔트리포인트는 기본적으로 `./dist/server/entry.mjs`에 빌드됩니다. 이 모듈은 Node `request` 및 `response` 객체를 지원하는 모든 프레임워크와 함께 사용할 수 있는 `handler` 함수를 내보냅니다.

예를 들어 Express의 경우:

```js title="run-server.mjs"
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
// astro.config.mjs 파일의 `base` 옵션에 따라 이를 변경하세요.
// 일치해야 합니다. 기본값은 "/"입니다.
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);

app.listen(8080);
```

또는 Fastify (>4)를 사용하면 다음과 같습니다.

```js title="run-server.mjs"
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = Fastify({ logger: true });

await app
  .register(fastifyStatic, {
    root: fileURLToPath(new URL('./dist/client', import.meta.url)),
  })
  .register(fastifyMiddie);
app.use(ssrHandler);

app.listen({ port: 8080 });
```

또한 `Astro.locals` 또는 Astro 미들웨어를 통해 액세스할 객체를 전달할 수도 있습니다.

```js title="run-server.mjs"
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
  const locals = {
    title: 'New title',
  };

  ssrHandler(req, res, next, locals);
});

app.listen(8080);
```

미들웨어 모드는 파일 제공을 수행하지 않습니다. 이를 수행하려면 HTTP 프레임워크를 구성해야 합니다. 기본적으로 클라이언트 자산은 `./dist/client/`에 기록됩니다.

### Standalone

standalone 모드에서는 서버 엔트리포인트가 실행될 때 서버가 시작됩니다. 기본적으로 `./dist/server/entry.mjs`에 빌드됩니다. 다음을 사용하여 실행할 수 있습니다.

```sh
node ./dist/server/entry.mjs
```

standalone 모드의 경우 서버는 페이지 및 API 경로 외에도 파일 제공을 처리합니다.

#### 사용자 정의 호스트 및 포트

런타임 시 환경 변수로 전달하여 standalone 서버가 실행되는 호스트와 포트를 재정의할 수 있습니다.

```sh
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs
```

#### HTTPS

기본적으로 standalone 서버는 HTTP를 사용합니다. 이는 HTTPS를 수행하는 프록시 서버가 앞에 있는 경우에 잘 작동합니다. HTTPS 자체를 실행하기 위해 standalone 서버가 필요한 경우 SSL 키와 인증서를 제공해야 합니다.

환경 변수 `SERVER_CERT_PATH` 및 `SERVER_KEY_PATH`를 통해 키 및 인증 경로를 전달할 수 있습니다. Bash에서 이를 전달하는 방법은 다음과 같습니다.

```bash
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs
```

#### 자산

standalone 모드에서는 `dist/client/` 폴더의 자산이 standalone 서버를 통해 제공됩니다. 이러한 자산을 CDN에 배포할 수 있으며, 이 경우 서버는 실제로 해당 자산을 제공하지 않습니다. 그러나 인트라넷 사이트와 같은 일부 경우에는 애플리케이션 서버에서 직접 정적 자산을 제공하는 것이 좋습니다.

`dist/client/_astro/` 폴더에 있는 자산은 Astro가 빌드한 자산입니다. 이러한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 내부적으로 어댑터는 다음 자산에 대해 이 헤더를 추가합니다.

```
Cache-Control: public, max-age=31536000, immutable
```

## 세션

[Astro 세션 API](/ko/guides/sessions/)를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 설정, 쇼핑 카트, 인증 자격 증명 등에 활용될 수 있습니다. 쿠키 저장소와 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수도 있습니다.

Node 어댑터를 사용하는 경우 Astro는 세션 스토리지를 위해 로컬 파일 시스템을 사용합니다. 다른 세션 스토리지 드라이버를 사용하려면 Astro 구성에서 지정할 수 있습니다. 자세한 내용은 [`session` 구성 참조](/ko/reference/configuration-reference/#sessiondriver)를 확인하세요.

## 환경 변수

런타임 시 [`astro:env`](/ko/guides/environment-variables/#타입-안전-환경-변수) 비밀 또는 `process.env`를 사용할 경우, Astro나 어댑터 모두 환경 변수를 자동으로 로드하지 않습니다.

일부 호스트는 빌드 및 런타임에 대시보드를 통해 구성한 환경 변수를 노출할 수도 있습니다. 특정 플랫폼에서 환경 변수를 설정하고 사용하는 방법은 호스트의 문서를 참조하세요.

자체 호스팅을 하는 경우에는 CLI 명령어나 구성 파일을 통해 환경 변수를 로드할 수 있습니다.

<Tabs>
  <TabItem label="인라인">
  ```shell
  DB_HOST=... DB_PASSWORD=... node ./dist/server/entry.mjs
  ```
  </TabItem>
  <TabItem label="dotenvx">
  ```shell
  npx dotenvx run -- node ./dist/server/entry.mjs
  ```
  </TabItem>
  <TabItem label="Docker">
  ```docker title="Dockerfile"
  FROM node:lts AS runtime
  WORKDIR /app

  COPY . .

  RUN npm install
  RUN npm run build

  ENV DB_HOST=...
  ENV DB_PASSWORD=...
  CMD node ./dist/server/entry.mjs
  ```
  </TabItem>
</Tabs>
